FLOSS Manuals Workflow
How do I make an updated version of a manual
'Real' versioning is not present in the Booktype software we use but we can follow the process below to achieve the same effect. This is especially helpful if we need to keep the old version of our manual online.
The process includes the following stages; clone our manual to a draft version, make revisions to the draft version, archive the previous version, rename the new draft version to take the place of the original version.
Clone existing manual to a new draft version
To start the process of updating our manual, we will keep the current version in place and clone it to a new location where we will undertake our updates.
As an example we can use the Command Line manual at this location: http://write.flossmanuals.net/command-line/
Navigate to the My Books Tab of My Dashboard and click on Import Book.
Fill out the dialogue form with the relevant details including the URL of where the current version of your manual is.
Be sure to select Booktype as the kind of import and to give your draft version a suitable and unique name.
You should then check your new draft and see that the contents have transfered ok. If there are small numbers of missing images you may need to reupload them. If there are major problems you can ask for help on the FLOSS Manuals discussion emails list (see the home page at http://flossmanuals.net for details on how to join).
You can then send this link out to your networks to ask them to join in the editing process.
Publish new draft online as your new official version
When you have finished editing your draft you should make the decision about if you want to replace the current version at the existing URL or keep both versions online and give your new draft a new name.
The latter is simplier but in this case, let's keep the URL at http://flossmanuals.net/command-line and archive the older version.
To rename and therefore archive older versions of the manual you'll probably need to contact admin at flossmanuals .net with your request as it is unlikely you will have the permissions to do this.
Generate pdf and epub versions of your Manual
To allow users to download your manual you should generate pdf and epub versions and include them on your Introduction page.
To generate your epub and pdf files go to the Publish Tab of your manual in edit mode
[screenshot]
For an example you can see the front page of the CSOUND manuals here - http://write.flossmanuals.net/csound
Publish new details to FLOSS Manuals front page
To make your manual appear on the front page involves updating a json file with updated details. An example is included here.
{ "title": "Chromium",
"category": "Internet",
"img_url": "index_fr_files/flossman_600.png",
"description": "When Google released the Chrome web browser in 2008, it also released its source code to the public through the Chromium project.",
"read_link": "http://write.flossmanuals.net/chromium",
"pdf_link": "http://archive.flossmanuals.net/_booki/chromium/chromium.pdf",
"epub_link": "http://archive.flossmanuals.net/_booki/chromium/chromium.epub",
"languages": [
{"name": "English",
"link": "http://write.flossmanuals.net/chromium"}
],
"keywords": [
{"name": "Browsing"},
{"name": "Web"}
]}
The front pages of FLOSS Manuals is a very simple web app that uses a data file containing entries in this format to create the books listed. It is much easier to maintain than a database.
There are two ways of updating or creating a new entry via email or through a git pull request. If you are not sure of what a git pull request is, then email is probably the path for you. Although if you are interested about using the very flexible and popular software git, then the could be a good project to learn with.
Publish via Email
Use the code shown above, known as a json file format, as a guide to create an entry for your manual. Descriptions should not be more than a few sentences long.
If you find the code above tricky to edit you can use an online tool for editing json files. Here is one http://codebeautify.org/online-json-editor
If you create your own front cover image then make sure it is of the dimensions 481 x 250 pixels
When you email updated details to admin @ flossmanuals. net
Publish via a Git Pull Request
If you are proficient with coding and use git hub you should revise this following file and make a pull request.
The file to model and update is here.
https://gitlab.com/mickfuzz/fm_en_splash/blob/master/data/book_details.json
Optional - Create a splash page
If you have made all the effort of writing your manual then you deserve to treat yourself and your team to a nice looking home page to point your readers towards when you are doing outreach and press work.
An example is here. http://openweb.flossmanuals.net/