A suggestion for better manuals.

Registered by Maxime Lavigne

Here, I am copying the question's description since the question expired.

I was looking at the Brewtarget user manual and this got me thinking about the fact that there must be a better way of managing contributions, language and formats.

Since the best community written book I know is pro-git, I went and looked at the technology they are using. First, they use the AsciiDoc encoding format that is very similar to Markdown. It is definitely clear enough that anyone could contribute after a quick glance at an example. Since it is similar to the Markdown format, I suspect some of you have seen similar examples when editing a Wikipedia article.

They are using the Atlas continuous integration manager for written publication but this is only an easy to use automation process. It could be easily emulated by someone on each release or, I imagine, a bash script.

The can then be compiled in an compiled html like we have right now, or a PDF, or most ebook format.

The other important point they have is that the book is in its own git repository and therefore contribution can be managed independently of the rest of the application. Which make sense since it is a different artifact. Since there is no clear solution to handle internationalization, every language as its own repository.

So there it is, I would like you opinion and comments on this. If you think this might be interesting, I could setup the basic infrastructure needed to replicate what we have right now and let everyone play with it.

Blueprint information

Not started
Maxime Lavigne
Needs approval
Maxime Lavigne
Series goal:
Milestone target:

Related branches




Work Items

Work items:
Setting up repository: DONE
Rewriting manual to Asciidoc: DONE
Reviewing with other developers: INPROGRESS
Documenting in a wiki page: TODO

This blueprint contains Public information 
Everyone can see this information.


No subscribers.