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

Status:
Not started
Approver:
None
Priority:
Undefined
Drafter:
Maxime Lavigne
Direction:
Needs approval
Assignee:
Maxime Lavigne
Definition:
Approved
Series goal:
None
Implementation:
Unknown
Milestone target:
None

Related branches

Sprints

Whiteboard

(?)

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.

Subscribers

No subscribers.