Formal Documentation Procedure/Requirement

[Nedmas]

Hey everyone,

So I'm wondering if there is any formal procedure or requirement for updating documentation when making significant changes to SS? Particularly for changes that break backwards compatibility or effect environment requirements.

The reason I ask is that I recently found myself in an awkward situation. I was working with a client who was hosting SS themselves, so when asked about server requirements I pointed them to http://doc.silverstripe.org/framework/en/installation/server-requirements. This was all fine until we tried to launch the site and found that they had installed the mysql module not the mysqli driver which is required. At this point I checked the requirements myself and realised that the documentation was actually wrong.

Now should I have checked the requirements before sending them to my client, absolutely! Have I sent a PR fixing the documentation yep https://github.com/silverstripe/silverstripe-framework/pull/2848.

However I think that there really should be some form of process in place to help minimise the risks of mistakes like this getting overlooked. The change from msql to mysqli happened over 2 years ago, which means the documentation has been incorrect for 2 years!

So I wonder if it would be helpful to outline some expectations regarding documentation e.g. what changes require what level of documentation, when is documentation required, who's responsibility is it to maintain certain types of documentation (changelog/requirements/references/guides)?

I hope that this doesn't come across as a rant, because that is not my intention! And I am aware that recent PR tend to include much more documentation which is fantastic. I'm also aware that ensuring that documentation is included is a requirement for the core team. Also just for the record I'm happy to help wherever I can.

What do others think? Is this already in place? Is it overkill?

Cheers,

Tom

[Will Rossiter]

This is one of the reasons we decided for bundling the documentation along with the code. Developers now have no excuse to not update it alongside PR's.

Updating documentation is listed as part of the check list http://doc.silverstripe.org/framework/en/trunk/misc/contributing/code#check-list (included in https://github.com/silverstripe/silverstripe-framework/blob/3.1/CONTRIBUTING.md) but at the end of the day it's the core teams job to ensure any PR includes relevant documentation updates.


On 15/02/2014, at 3:21 am, Nedmas <tom.d...@studiobonito.co.uk> wrote:

>

[Daniel Hensby]

I suppose it's a balance between encouraging contribution to the codebase from the community and keeping high quality commits (eg: including tests and docs).

I think if all PRs had the requirement of docs and tests then the barrier to contributing would be too high and it'd lead to too many abandoned PRs - "Oh, I'll do the tests and docs when I get time"... If this is a true requirement then if a PR has been opened that's got all working code but is lacking docs then a core maintainer should take ownership and add that in.

Also, the docs are a bit tricky and it's hard to know where a doc needs updating when you change code, or maybe the code you changed has no docs, so you're not sure where to add it.

Overall, I think there needs to be a big effort to improve the docs overall. They are seriously unloved

[Nedmas]

Hey Will thanks for the info regarding the contributing check list, that's a really helpful list that I'd forgotten about. And I think that the decision to bundle in the documentation was a great step towards improving the quality of documentation and PR's. But I think that there's still a lot more we can do.

Daniel I agree with you that we need to get a balance between encouraging contributions and striving for high quality commits. And I think like Will said at the end of the day it's the responsibility of the core team to ensure PR's include documentation, and so drive quality and encourage contribution (which I think they're doing well).

I just want to work out if there's anything we can do to make it easier to contribute documentation. Because I agree with Daniel that the current documentation is a bit tricky. I constantly find myself flicking between the reference and topic sections because I can't remember where stuff is!

Out of interest is there anyone at SilverStripe or in the community that currently has ownership/responsibility for documentation?

Would it be worth allocating someone (or a group of someones) to be responsible so that there is a single place for reference when it comes to writing documentation?

Also is it worth setting out to review the documentation to make sure that there aren't anymore mistakes that have been overlooked?

[Ingo Schommer]

@Nedmas: Regarding flicking between “topics” and “reference”,

do you have any specific suggestions on what to combine?

Maybe you or Daniel are even keen to give that a shot?

I think if we’ve learned anything over the last years,

its that we can’t wait for some “content person” to magically go and fix things in the docs.

Its up to devs to do that, even if it means a slightly odd sentence here and there :)

Maybe you want to start a Google Doc with a proposed structure,

or even just a list of the most confusing or outdated areas in the documentation?

---

Ingo Schommer | Senior Developer
SilverStripe (http://silverstripe.com)
Skype: chillu23

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev.
For more options, visit https://groups.google.com/groups/opt_out.

[Nedmas]

@Ingo: Yeah I was thinking when writing my previous post that I was probably creating a job for myself :) I'm not sure I'm the best person to be working on this, but like you said we can't wait around for someone to come and sort it for us!

I've read the article you reference in the documentation about what to write (http://jacobian.org/writing/what-to-write/) and I guess that's what partly inspired the current reference/topics divide. I like what it's getting at by thinking about who you're writing for and what level of detail is required. But I kind of regard api.silverstripe.org as what he describes as reference and the whole of doc.silverstripe.org as what he describes as topical.

I think it would be worth looking at how the documentation is structured and thus how you navigate it. I'm happy to come up with a proposal and submit it for discussion.

@Daniel: What are your thoughts on the above? Would you be interested in helping create a proposal for restructuring the docs?

[Daniel Hensby]

I agree that it isn't clear what is topical and what is reference. I feel the docs need a complete overhaul to make them useful from having tutorials to get you through the learning curve to cheat-sheets on templating and so on.

I am becoming a bit of a lover of Laravel and their docs are nicely structured (http://laravel.com/docs) but I do find them a bit light on detail in places.

The other tricky aspect is whether we write docs for the framework or the framework and CMS. Should they be together or separate? At the moment they are together, but this doesn't make sense for people who just want the framework.

Lastly, there are lots of features that are completely undocumented, does anyone have a clue how to use the Makefile in silverstripe-installer?

I'd be happy to give my thoughts to improve the docs, but at the moment don't have time for much more than direction...

Daniel Hensby Director

e: daniel...@betterbrief.co.uk t:  020 7183 9266 w: http://www.betterbrief.co.uk

--

[Ingo Schommer]

Hey guys, just had a browse through the Laravel docs,

and I like how they’ve condensed it into two dozen pages

with a light structure around it (“getting started”, “learning more”).

I think there’s too much fragmentation in the docs, and we should

consolidate into longer single page docs. I’ve started a doc

with suggestions, everybody’s welcome to add and comment there.

But even more welcome to transform some of these ideas into pull requests ;)

https://docs.google.com/a/silverstripe.com/document/d/1GhzKaZAluLTY8KIFy7-uPRb7H9LnPx5Dp67oAHKLhp0/edit#

[Daniel Hensby]

Ingo, yes, I like that about Laravel too, a nice layout.

Without wanting to dismiss the document (which I'm not and ideas should definitely go there), I reiterate that I think the docs need an overhaul and perhaps a nice IA needs to be the starting point.

Also, what is the focus of the docs, Framework or CMS & Framework? There are pretty much zero docs on using Framework without the CMS and all the guides seem to relate to Pages and CMS.

[Ingo Schommer]

Small and achievable steps, Daniel ;)

On focus: Both CMS and framework for now. 

Separating that out will be quite challenging,

particularly if you consider the docs user experience

for the 95% of devs who use both together.

But open for suggestions :)

[Daniel Hensby]

True. Though one of Josh's favourite sayings at the moment is "don't confuse movement with progress", so whilst we may outline achievable steps, will we have progressed from where we are now?

I agree that we should probably keep the docs fairly closely coupled for now (though I'd prefer them to have some degree of separation).

[Nedmas]

So firstly I'd like to apologise for dropping off the face of the planet! (Life got pretty busy but that's still no excuse for disappearing)

Secondly I'd like to press on with this issue and see if we can get some momentum behind updating the docs!

In summary so far I think everyone agrees that the docs need some love, that improving the clarity of the docs is important, and that the long term goal is to see the docs structure improved. To that end I think that along with and to help with the de-fragmenting of the docs that Ingo has started we also need to start restructuring the docs as Daniel suggests. I believe that it is possible to start that process now and that the first baby step is to separate out what we have into framework and cms.

I have written a quick doc that outlines the beginnings of this restructure which if it looks ok to both of you I'm happy to expand to cover all of the current docs.

https://docs.google.com/document/d/1urnRVr01GH71m3MkgyvmyU-rWQg3my4f6irC_DUvuc4/edit?usp=sharing

Again sorry for falling silent, I really do think that this is important and I hope we can push this forward.

Tom 

[Ingo Schommer]

Hello Tom!

I’ve been reluctant to split up the docs between cms and framework 

precisely because I think it’ll make the docs less clear and less coherent

to the majority of our devs, which use the cms and framework together. 

The devil is in the details, for example you need to rewrite code

examples in UploadField to use DataObject/Controller rather than Page/Page_Controller

because UploadField would live in the framework docs:

http://doc.silverstripe.org/framework/en/reference/uploadfield

That being said, its an overdue change if want to be serious about

promoting the framework module as a standalone entity.

We just need to be careful to keep the main use case (cms+framework)

in mind when doing the information architecture.

How would you envision a documentation landing page for this split?

That might be a good starting point to validate the approach.

Thanks

Ingo

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev.

For more options, visit https://groups.google.com/d/optout.

[Nedmas]

Hi Ingo,

I completely agree that what ever changes are made need to preserve the focus on the main use case.

But that splitting the documentation is a key step in the development of SS as a framework.

Initially I envision this being a relatively transparent change, so that on visiting http://doc.silverstripe.org/ people will be presented with essentially the same page they are currently. However that page will live in the cms docs, so instead of being forwarded to /framework/en/ you will be forwarded to /cms/en/.

Also the links on the landing page will not all be for docs in cms but some will be for docs in framework and cms will now be listed alongside framework under modules.

The area I am least sure on is what happens to the side navigation?

I think going forward it would be good to have it different for cms/framework to allow more focused navigation e.g. more tutorials and howtos in cms and more references in framework. However I think this needs to be planned out and driven by content, so for the time being I maybe it would be best to duplicate the side navigation in both cms/framework but look to change that as content improves?

Let me know what you think,

Tom

[Ingo Schommer]

The side nav is generated based on the file list.

The underlying docsviewer module works based on modules and distinct paths,

it doesn’t allow any cross-over between modules, like showing a combined file list between two modules.

Technical constraints we can work around of course. 

But even from an IA perspective, I’m not sure how that would look, 

for example would you have two “topics” links in the sidebar?

Or “flatten” the docs in the cms/ underneath a single entry?

I don’t really have time to think this through, which is why I suggested

that you start with a landing page IA (maybe as a rough wireframe?).