Writing documentation

[Marijn]

Hi,

A couple of days a go I opened an feature request (IVariableSource for app settings) for which functionality already was available, but lacked documentation. I thought I'd add the documentation myself. I've managed to edit some source files using notepad++ and successfully compiled the documentation.

Now I've got a couple questions about writing and contributing documentation.

1. What tools do you use to write documentation? For minor changes it's ok to use notepad / visual studio, but I find the Docbook format a royal pain to write a couple of paragraphs in. (you guys should try Sphinx)

2. Is there any form of guideline (e.g. language, code formatting, ?) for writing documentation?

3. I saw issue 491 on publishing a development version of the docs as part of the nightly build. Any ideas on that subject? A relatively easy approach could be to publish the documentation build output to the github pages for springsoure/spring.net. The docs would then be available at http://springsource.github.com/spring-net/.

Regards,

~Marijn

[Steve Bohlen]

I agree its beyond troublesome to make anything but trivial edits in docbook files using non-docbook-capable editors (notepad, etc.). The easiest (and free) docbook editor that I can recommend is XmlMind (http://xmlmind.com/xmleditor/) -- its what we use at SpringSource to author/edit the reference docs.

Discussions/suggestions in the past about switching to alt doc formats have always bogged down around the effort required to convert the existing reference docs to the new format (and there are of course a lot of existing docs that would need to be converted). Any move to an alternate format would need to take into account ease of transition of existing docs (and post-migration clean-up, etc.) as part of the value proposition. That said, we're certainly open to evaluating alternate doc-gen platforms in this context.

re: SPRNET-491, its probably pretty simple to post the HTML docs from the nightly build to some externally-navigable URL. I'm intrigued by the suggestion of using github pages for this. I don't have any experience pushing anything other than wiki markdown to github pages -- can it 'accept' direct HTML (as would be the result of our nightly builds) or would we have to first find a way to 'project' the HTML output into equivalent markdown?

Thoughts welcome as always,

-Steve B.

[Marijn]

Yes, github accepts html: http://serra.github.com/spring-net/r...tml/index.html.

There are various ways to automate this into the build process; I've got a bash script that about-does it. Not sure how to implement this in nant, though.

Tricky bit is that you (likely) don't want to keep diffs on your generated html in the repository.

Regards,

~Marijn

[Steve Bohlen]

Hmmm...I agree w the desire to avoid storing DIFFgrams of the HTML form of the docs in the repo. Perhaps that's more of a reason to post it somewhere other than github pages. We already have a scripting process (powershell invoked by NANT in this case) responsible for moving the daily build artifact (zip) to the server and making it available. I'm thinking that using some of that same infrastructure to post the HTML doc-gen output might make more sense (since both could be considered 'nightly build output' that needs to be handled similarly in re: making them publicly available.

-Steve B.

[Marijn]

That would work too, of course.
Note that there are "git tricks" that would prevent the history of html files being tracked; you can only keep the state of the last commit.
I have been experimenting with this approach, got it to work, but found it somewhat opaque. It involved copying scripts and switching between branches in the midst of a publish run.

I'll post here if I think it might be of interest.

~Marijn

[Steve Bohlen]

I'm inclined to think that all those careful 'tricks' would result in a solution that's overly complex. I'm in the process now of wiring the CI server to post the doc-build-latest HTML output to S3 where it can be publicly referenced from the springframework.net site (and elsewhere). It seems to me to be a cleaner/less-brittle approach (so far, at least ).

Thanks for the suggestions all the same -- if for some reason the post-to-s3 approach ends up at a dead-end, I'll come back to ask you more details about your offered github-based approach.

-Steve B.

[Marijn]

I've downloaded the XMLmind editor and made some trivial formatting changes. It works OK, but for some reason, I'm not able to open all documentation sources.

There files I can open and edit; for instance objects.xml and preface.xml work fine.

But I can't edit quickstarts.xml, I get the error

The entity "pooling-example" was referenced, but not declared.

When opening remoting-quickstarts.xml, dao.xml and aop.xml, I get the status message that the document is invalid, but I am able to edit the file.


What is your standard workflow when editing documentation? I've got the feeling I'm missing something (obvious?) here.


~Marijn

[Marijn]

I can't imagine that approach coming to a dead end

I think it's good NOT to use gh-pages to publish the docs.
As I said,I got the gh-pages approach to work, but it's a complex approach for something that should be simple.

Using gh-page for a website is great, because you get version control for your source and a neat website in one.
But if you don't want version control of your sources, you shouldn't use it.

~Marijn

[Steve Bohlen]

I see that you posted a pull-request for some doc edits; does that mean that you found a way around this issue or that you're just ignoring it for the time being (e.g, is this still something you need assistance with)? Let us know and I will see if we can puzzle out what might be 'wrong' for you.

-Steve B.

[Marijn]

I'm working around issues posted above. Some general pointers on how you guys edit the docs would help. Or a "how to contribute to the docs" sticky or wiki page, which would be useful for other contributors too. Just some guidelines so that I know I'm not too far off track and don't waste too much time.

Thanks,

~Marijn