Restructuring our developer documentation

[Sam Minnee]

Restructuring our developer documentation
===========================

Hi everyone,

The doc.silverstripe.org documentation wiki leaves a bit to be desired
in terms of completeness and IA. Part of the problem is the
infrastructure that we are using to manage the documentation; I would
like to suggest a change.

Problems
--------

In particular, I don't think that a wiki is appropriate. Using a wiki
for product documentation has some disadvantages:

* When a feature is added to trunk, there's no clear place to stage
documentation until the next release
* It's difficult to see the documentation for 2.3 vs. 2.4, etc.
* When a community member contributes a patch, there's no clear place
to stage documentation until the patch is accepted, and included in
the next release.

These process issues are one of the reasons why we have difficulty
keeping documentation up-to-date.

Recommendation
---------------

Ingo and I have spent some time discussing this and we'd like to
propose this alternative approach.

* Documentation lives in the docs/ directory of each module. sapphire/
docs/ would contain framework documentation and cms/docs/ would
contain CMS documentation.
* These docs/ directories would be protected by .htaccess files so
that the documentation wasn't accessible over the web.
* All the documentation would be in the form of Markdown files. We
would migrate the current doc.silverstripe.org content into these
files.
* Embedded images will be stored in
* dev/docs/ will show a simple controller for exploring the developer
documentation. It would provide:
- a table of contents of the documentation from all the modules
- a simple plaintext search
- a view of individual document pages in formatted HTML
- a view of all the documentation in one big formatted HTML page,
for printing
* doc.silverstripe.org would host publicly accessible copies of the
dev/docs/ system, for each version of SilverStripe that contains this
documentation system.

The key to this approach is to bundle the documentation source in with
the application. In this sense, it is similar to the approach that
Django take. With this in place, we can also request amendments to
documentation as part of changesets that enter the repository, in the
same way that we might request a unit test before we merge a patch.

Also important is the choice of Markdown as the format for storing the
documentation. We're recommending Markdown because:

* it is designed to be easily readable in it's raw format, and easily
edited. As an example, this post has been written in Markdown format,
although you might not have noticed. ;-)
* it has good support code blocks, including code blocks within bullet-
point lists
* it is well known and well supported. For example, TextMate has a
markdown module.

Note that we may want to use a variant of Markdown if we find that we
need the extra features, such as tables. We'll cross that bridge when
we come to it.

One unanswered question is what to do with the Disqus comments.
Should we migrate relevant content out of them and then drop them from
doc.silverstripe.org?

What do people think of this approach?

Would anyone be available to help with the migration effort?

Thanks,
Sam

[Simon J Welsh]

What would happen to all the extra content? Like recipes and the
tutorials? Would having an empty "module" with just these extra useful
tidbits (and maybe some example code) help to make sure they don't
disappear into Skynet?

---
Simon Welsh
Admin of http://simon.geek.nz/

Who said Microsoft never created a bug-free program? The blue screen
never, ever crashes!

http://www.thinkgeek.com/brain/gimme.cgi?wid=81d520e5e

[Will Rossiter]

One unanswered question is what to do with the Disqus comments.
Should we migrate relevant content out of them and then drop them from
doc.silverstripe.org?

Considering most of them are spam, questions, or off topic I think pulling content from the few decent ones and then deleting them all should be a decent way to go.

One question would be over the size of silverstripe with these docs bundled. Will bundling all the screenshots and diagrams for documentation pages cause a much larger download? I know removing jsparty in 2.4 is going to reduce the size overall but if adding built in documentation adds say 50mb to the download which over 20 sites on a server equals pretty much a gig of space taken up. Perhaps ways round reducing the size / removing docs on live sites.

Currently users can edit doc to fix typos, add sections etc without too much hand holding, if this is moved to sapphire / cms folders is there going to be a nice way for the community to edit docs themselves or are they going to have to send through patches to the core team - meaning someone will have to check them, merge them back.

Also do you see the pages like the tutorials categorized into cms or sapphire/ which aren't really related to individual modules, just general SS information. I see bundling the HTML/CSS docs into the themes dir rather then cms/ or sapphire/. Recipes would be left on the wiki? Installation docs?

Cheers,

--
Will Rossiter | Developer
SilverStripe
http://www.silverstripe.com

Mobile: +64 27 389 3454
Office: +64 4 978 7330 ext 58
Skype: will.rossi

Level 5, 97-99 Courtenay Place
Wellington, New Zealand

[Andrew Short]

I think that coupling documentation to the source is a good idea. My only concern is that we would be further bloating the core download with documentation text and images. However, is this really an issue? I imagine that the size of all the docs would add up to be a fair amount, but they do provide a lot of usefulness. The only real issue with space and download speed is if you're uploading files one by one via FTP, instead of directly grabbing files over the server or using source control.

On the other hand, AFAIK alot of shared hosts require you to upload files by FTP, or don't provide shell access. Perhaps an elegant solution would be to build a download page like that at http://www.kohanaphp.com/download or http://mootools.net/core - which allow people to build a custom core download with added modules. Allowing people to exclude documentation and tests would mean alot of files could be eliminated. This would also make it easier for people to collate modules, as well as prevent problems with module downloads being named things like "userforms-r2139" and causing issues.

Andrew Short

[Sam Minnee]

Will and Andrew both raised the issue of download size.

We should keep an eye on the download size. *If* it became a problem
we could potentially look at hosting the images externally on an
external host such as assets.doc.silverstripe.org. The version
management issues aren't such a problem with assets, because you can
change the documentation test to point to unique, immutable filenames
(for example by including a version number in the file name).
However, I would probably advocate leaving the assets inside the
repository until we're sure that that's a problem.

The Kohana-style download builder would be a good idea - we could also
have an option to exclude tests, for example.

In addition, deployment tools could be improved to be more precise
about what gets transferred to the production site.

[Sam Minnee]

It may be that there is *some* content that is more usefully kept in a
collaborative wiki-style form. I think that the recipes area is the
main candidate for this. We certainly wouldn't want to throw away
useful content. However, we would want to throw away obsolete
content.

I believe that some of the recipes cover parts of the system that
haven't been documented. These recipes should be converted into
"real" documentation and bundled in the manner described above.

[Nicolaas Thiemen Francken - Sunny Side Up]

I dont really agree with this method.  Imagine you had PHP installed and all of the help-files where within the code.  I just dont think that this really works. I much prefer to go to www.php.net and sometimes i see a flag like "not available before 5.3".  I can search it from anywhere, I can refer to it easily, I can add to it, etc.... All of this would be lost if we took on the new approach. 

I agree with linking the help files to a release, but does this need to be a physical "lets sit together" scenario.  Is there anything better that we can come up with ? (e.g. this code is available from 2.3)

Download size is definitely an issue.  Many hosting platforms provide limited download space and uploading a site using FTP would take even longer (unless you started to manually delete the docs, etc....)  I know that FTP is far from ideal, but from my experience most SS developers actually do this.

Most of the time, when I am trying to find out how something work, I look at the actual code.  If we were to put the documentation with the code then why not just improve the inline documentation a bit more, while keeping tutorial style stuff on doc.silverstripe.com.

Just my five cents worth, hope that this aids to the conversation.

Nicolaas

[Sam Minnee]

I think that one thing that is clear here is that the our näive
approach to packaging a release - simply create a tar.gz of whatever
is in subversion - is no longer appropriate. The concerns that
Nicolaas raise are due to the fact that the needs of people working
*on* SilverStripe are different from the needs of people working
*with* SilverStripe. All of the advantages that I expressed are
advantages for the people who need to keep documentation in sync with
code.

The code repositories are designed first and foremost for people
working on SilverStripe, and the packaged releases should be designed
for people working with SilverStripe.

As such, perhaps our packaged releases should be built to exclude the
documentation and maybe the tests?

The other thing to make clear is that we're not suggesting that
doc.silverstripe.org gets shut down; just that its content would come
from a new place.

One thing that we wouldn't be catering for are people who work *with*
SilverStripe, but opt to download it via subversion. One solution to
this would be to have the packaged releases (ie, docs and tests
removed) available in somewhere Subversion. But this might be
overkill - people can use our subversion repository as a convenience,
but I'm not sure if we need to start providing packaged releases
available for download in multiple protocols.

On Oct 27, 5:22 pm, Nicolaas Thiemen Francken - Sunny Side Up

<nfranc...@gmail.com> wrote:
> I dont really agree with this method.  Imagine you had PHP installed and all
> of the help-files where within the code.  I just dont think that this really

> works. I much prefer to go towww.php.netand sometimes i see a flag like

[Nicolaas Thiemen Francken - Sunny Side Up]

As such, perhaps our packaged releases should be built to exclude the
documentation and maybe the tests?

I never use the packaged releases, but I am sure all the people that do will LOVE not having to dowload the tests.

[Simon J Welsh]

I've flicked through a small bit of the SilverStripe book and noticed
that there is some links to doc.silverstripe.com. I think that making
these no longer valid could be bad. Just pointing this out so you
don't forget to add in redirects to the new content.

Though it may make sense to create a doku.php that tries to redirect
old links to the correct new pages (when they're known) so as few as
possible external links (#silverstripe logs, links in the forum, helps
sites, etc...) break. This script could then possibly be expanded to
act like the default 404 search function that php.net uses.

[Sam Minnee]

> Though it may make sense to create a doku.php that tries to redirect  
> old links to the correct new pages (when they're known) so as few as  
> possible external links (#silverstripe logs, links in the forum, helps  
> sites, etc...) break. This script could then possibly be expanded to  
> act like the default 404 search function that php.net uses.

That seems like a good solution to the link-breaking problem. Chances
are, it'll just be a gigantic array of old-page-id to new-url.

Of course, fixing old links is one of the last things that would need
to be done in the process. But thanks for the reminder. ;-)

[howardgrigg]

Just my 2c,

I also think that it's important to keep download (and upload) size
small mainly for three reasons;
1. As others have mentioned FTP is a dog and that's how most/all
new users will be introduced to SS,
2. A number of small sites still use shared hosting so a 80mb CMS
install which the current trunk checkout is is quite a hefty portion
of their shared hosting space,
3. Perception of the CMS/Framework as bloated, new users may feel
that the large file size is due to crappy bloated code rather than
realising it's the docs.

Because of this I definatly think that a core version without docs
(and tests) would be required, also personally our sites are developed
with SVN and externals linked to version branches for ease of upgrade.
It would be nice (although maybe unnecessary) to be able to link those
to 'core' versions.

Also for new users I think that some thought should go into making the
documentation more visible, which i guess this change would provide,
as with the current system a lot of pages are orphaned without an
obvious way to access them.

As for the recipes I see these as not really part of the core
documentation but maybe have a better home on a site like Aram's
ssbits.com?

Would be great to see something happen with the docs!

On Oct 27, 6:05 pm, Nicolaas Thiemen Francken - Sunny Side Up

[Marcus Nyeholt]

I agree that including the raw documentation source alongside the actual code for the module is the way to go; aside from 'keeping it all together', the versioning aspect will greatly help as things are updated both code and doco wise. I'm also voting that including this info in a download is probably not necessary, and would have more of a negative impact than positive.

Something I've been playing with over the last couple of weeks is phing (http://phing.info/) for automating some of the stuff I commonly do with, of which creating a minimal package for deploying to a server is one of them. Pruning various directories/files is a trivial thing to do, but it might also be useful for doing things like documentation builds etc.

Another thing I've been thinking about, and making tentative steps towards, is a SilverStripe based pattern library along the lines of Yahoo's library (http://developer.yahoo.com/ypatterns/). It takes inspiration from a GoF style software pattern, but is a bit higher level and speaks to a broader audience. Still in the thought/planning stages at the moment though

[dalesaurus]

My $0.02 is that

1. Bundling "core" documentation, as an option, would be great
2. There should be a separate collaborative area for recipies/etc (I
am a huge wiki proponent)
3. Keep "core" (how to setup XXX, available functions, etc)
documentation separate from "everything else" (images, recipes,
snippets, etc)

The question is how to keep the line between the two. A common
approach I've seen is keeping the "core" docs as the PHPDoc extracted
information, but having a wiki of sorts for "everything else". Its
the same idea as reading the man page versus going to serverfault.com.

As for comments, I think most can be tossed. I am not a fan of Doku
in general. Having Comments on a Wiki is a contradiction in the first
place.

I have use TWiki (and FOSWiki) before to handle the versioning issues
mentioned above. Creating a separate web for each major release
allows reuse-with-separation between releases. Atlassian also offers
most of their products free for Open Source packages, and Confluence
is pretty advanced.

I'd be willing to put some time into the wiki part of things (once my
current contracts slow down...and I finish that Exceptions bit).

> SilverStripehttp://www.silverstripe.com

[Sam Minnee]

> The question is how to keep the line between the two.  A common
> approach I've seen is keeping the "core" docs as the PHPDoc extracted
> information, but having a wiki of sorts for "everything else".  Its
> the same idea as reading the man page versus going to serverfault.com.

I think that Django do this well, and is a good example of what I had
in mind with the original proposal.

Here's the doc site: http://docs.djangoproject.com/en/dev/
Here's the doc source in the repos: http://code.djangoproject.com/browser/django/trunk/docs
And here's their wiki: http://code.djangoproject.com/wiki/DjangoResources

The wiki contains unstructured documentation collected from a large
number of ppl. There's not a lot of cross referencing.

[Morven Lewis-Everley]

I think I agree with Dalesaurus, I am quite a fan of wikies, but doc.silverstripe.org is starting to feel quite cluttered.

I am a bit of a noob when it comes to Wikies (I very rarely need to deploy them), but is there not a way of tagging pages with relevant version numbers?

I feel that the wiki would be vastly improved with some layout and IA tweeks. For example, some fixed navigation, so you can easily skip sections and also from the layout being a bit wider. I find the content can get quite difficult to read because its container is so narrow.

I don't have an issue with bundeling documentation with the packages, but the joy of the colaborative documentation is that its quite easy for you to tidy up or add to those docs. I think you might be less inclined if amending documentation meant you had to edit source code then submit a patch and wait for acceptance or not.

Just thought I would voice my thoughts on the matter :)

Mo

[Michael Gall]

I don't have an issue with bundeling documentation with the packages, but the joy of the colaborative documentation is that its quite easy for you to tidy up or add to those docs. I think you might be less inclined if amending documentation meant you had to edit source code then submit a patch and wait for acceptance or not.

It is also worth noting that checkin rights aren't particularly thrown around, so having them in svn adds a pretty big barrier to entry of contribution. 

Michael

[Sam Minnee]

> > the joy of the colaborative documentation is that its quite easy for you to
> > tidy up or add to those docs. I think you might be less inclined if amending
> > documentation meant you had to edit source code then submit a patch and wait
> > for acceptance or not.
>
> It is also worth noting that checkin rights aren't particularly thrown
> around, so having them in svn adds a pretty big barrier to entry of
> contribution.

Other projects have addressed this by including doc editing systems
that commit to the relevant files. In some these changes have been
committed to a docs branch, that could be regularly rebased to trunk
and/or merged back into trunk, on top of a VCS such as git.

This would be an option, but unless we can integrate an off the shelf
tool it would require a fair bit of infrastructure work, and so would
be unlikely to appear out of the gate. It could, however, be a nice
project for someone to pick up after the migration has happened. A
quick search uncovered http://el-tramo.be/software/wigit which could
be a good starting point. I think attacking the editing/contribution
problem now would be a bit premature, but it's good to know that there
are options.

Note that the editing facility would also be made substantially easier
if there was a git repository containing the source code. But that is
a separate discussion. ;-)

Regardless, although community contribution is a concern, I don't
think it's enough of a reason to stick with a wiki for core developer
documentation. The current wiki is broken, and unless it has the
branching/merging capabilities of a source code VCS, it's going to
remain broken.

We need a way of tracking documentation changes in line with source
code changes - whether those changes are commits to trunk, branches,
remote cloned repositories, or patches. I can't see any other way of
doing this apart from putting the content into the repository.