Documentation 3.5 Improvement

[kiwisincebirth]

Observations

• The User guide has grown to become quite large (167 pages), and covers a wide range of topics, not just how to use RomWBW. This probably since this is considered the primary / default document that everyone reads
• The errata.MD document seems like it should be retired (3 paragraphs) and it content moved elsewhere

Ideas for reducing User Guide

Create a new "Hardware" document.

• The purpose of this would be to cover hardware specific information.
• Initially move Appendix A (50 pages) from User Guide into this new document. While the existing section is named "Pre-built ROM images", it could be renamed to "Supported Hardware Platforms"
• Also potentially move Section 14 "UNA Hardware BIOS" from user guide to this new document.
• Noting the existing Errata MD could be renamed to Hardware MD since the Errata is all about hardware anyway

Create a new "Introduction" document

• Which provides an overview (a description) of RomWBW, and would become the starting point for all documentation.
• Sections 1, 2.3, and 16 thru 19 (8-9 pages) of the UserGuide should be moved into this new document.
• Add a new section to describe the documentation (PDF's) for the project, ie. what is it, whom should read it.
• Add a new section to cover Release Notes, adding 3.5 initially, describing the main new features of the release

Other minor changes to User Guide

• Appendix B "Device Summary", could be moved into the the "SystemGuide", its primarily just a list of hardware device drivers, and there is a lot of crossover in system guide with this list.

The point here is that user guide just becomes a How to Use - style of document - it shortens it to something more manageable, while adding a couple of new documents that can be extended latter.

[wwarthen]

Thank you @kiwisincebirth.

I agree with almost all of this. I would like to keep the Release Notes as a separate document because I want to ensure it is extremely simple for users to access via links I intend to place in many places. I prefer users not need to look through another document to find the Release Notes.

I am swamped right now (testing v3.5 and some personal stuff). You are welcome to pursue these doucmentation improvements, otherwise I will try to take care of it prior to finalizing v3.5.

Thanks, Wayne

[kiwisincebirth]

See PR #494

After I did most of the work, i went to update /source/doc/readme.md (contributions list) then discovered

• this readme seems to be an extract of various sections from the user guide (copy/paste)
• the readme is actually very close to the sections that I have extracted from UserGuide and included in the NEW Introduction.PDF

So basically my idea of an Introduction PDF document is closely aligned to content behind the projects readme. Noting : I did do some reorganisation of Introduction.PDF to provide slightly better flow.

So where did I leave it.

• I left the Readme.MD intact as didn't want to mess with it. It can be compared to the Introduction.PDF
• there is alot of duplicated content between these 2 documents, (no different to before), but now its all isolated in Introduction.PDF

However: There is an opportunity to combine / reduce to a single Readme/Introduction document, removing alot of duplication.

The primary differences between the 2 documents are:

• Sections "1.1 Conventions Used", and "4.2. Related Projects" in Introduction do not appear in Readme
• In Readme section "Installation & Operation" does not appear in Introduction.PDF

[wwarthen]

The high-level ReadMe document has always been an extract of portions of the User Guide. I started to resync ReadMe with the new Introduction document, but soon realized that the content of the Introduction document was actually very similar to the ReadMe. Now that we have the Introduction document, does it make sense to use it instead of ReadMe?

[kiwisincebirth]

The high-level ReadMe document has always been an extract of portions of the User Guide. I started to resync ReadMe with the new Introduction document, but soon realized that the content of the Introduction document was actually very similar to the ReadMe.

So you came to same realisation.

Now that we have the Introduction document, does it make sense to use it instead of ReadMe?

I don't think we do. That was my point above, but wanted your buy-in since it affects to project level readme. In summary think want is needed is to Delete /source/doc/ReadMe.MD, and Update the build scripts to use Introduction.MD in its place.

[kiwisincebirth]

The only other tweak's I would be to

• move a section called "Conventions Used" out of Introduction, and back into User Guide (under Preface section), as it is out of place in project level description.
• include "Installation & Operation" in Introduction.PDF, copied from Readme

Which is addressed in #495

[wwarthen]

Hi @kiwisincebirth,

I somehow missed your entire post that included the comment about the ReadMe and the Introduction being so similar. Very sorry about that.

I think we are in sync and will review your latest PR shortly.

Thanks, Wayne

[kiwisincebirth]

I am going to close this discussion as complete