Migrate / Create style contribution guide for the user documentation

[michaelmcandrew]

This should reference the global style guide and include user guide specific stuff, for example

• how to reference technical materials in an accessible / non intimidating way. See Ensure all references to technical subjects are prefaced with accessible text #139. Other thoughts on what to include here welcome.

• no code in the user guide

[please add further thoughts below]

[seancolsen]

Perhaps this is already clear, but I want to point out that Documentation Style Guide (which is stored in the Dev Guide) is intended to apply to all documentation, including the User Guide.

For example it already has this content:

For the User Guide only: We try and limit the content to tasks that the user can perform from the front end. This means that we don't go into detailed steps about installation or system administration tasks. We do however let people know that there are system administrator tasks out there (setting up an SSL certificate, configuring CiviMail etc.) and point them in the right direction when they want to know about those tasks.

I think it's still a good idea to implement your two suggestions above. I just wanted to make sure that people know about the Style Guide and what it currently offers.

[michaelmcandrew]

Maybe the documentation guide should go in the civicrm-docs repo? Or have general stuff there, and guide specific stuff in each guide. Having user doc stuff in the developer guide seems a little funky (low priority).

[seancolsen]

Here's my logic for putting the style guide in the Dev Guide:

1. I think it's useful to have all the meta-documentation (i.e. docs about documentation itself) in one place (e.g. how to contribute, markdown syntax, markdown standards, style guide).
2. Markdown syntax differs slightly across platforms (e.g. GitHub does not support admonitions)
3. MkDocs is great, and we have a lot of momentum with it, so I'd like to focus all our docs efforts there as much as possible.
4. Because of (2) and (3), I'd like for whichever place we choose for (1), to offer a primary reading experience within a book (i.e. with MkDocs) and not on GitHub. This way the meta-docs can appropriately document markdown as it will be shown in the platform we intend to focus on.
5. Because of (1) and (4) it becomes necessary to choose one book to hold all meta-docs.
6. We don't have enough meta-docs material to justify a dedicated book
7. Because of (5) and (6) we should choose one of the guides (user, admin, or dev) to hold the meta docs
8. All developers should be participating in documentation, at least to a small degree
9. Very few users/administrators (who are not developers) will ever participate in documentation
10. Because of (8) and (9), I choose "Dev Guide" to fill the need in (7)

Here's another way to say most of the above... The CiviCRM project produces a product. Part of that product is the code, but another part is the docs to go along with the code. Thus "developing" encompasses the production of documentation.

[michaelmcandrew]

The choice makes sense @seanmadsen.

We don't have enough meta-docs material to justify a dedicated book
Very few users/administrators (who are not developers) participate in documentation

Don't have very strong opinions but If at some point the above changes, we could reconsider. e.g. this stuff is handy https://github.com/civicrm/civicrm-docs/blob/master/README.md.

Doesn't have to be a huge book :)

Keeping this issue open since there is still work to be done (if you skip over the part where we got side tracked :) )

[joannechester]

I do not like the idea of having to go to the Dev Guide to find the style guide, particularly when it contains information about what should or should not be included in the User Guide.

My opinion, as a non-developer who has been one of the most consistent contributors to the user guide over the last 4 year, is that we need a separate Style Guide book even if it only contains one chapter.

[seancolsen]

I'm open to a separate book and happy to help with the work to create one if that's what people want.

Question for you @joannechester: with a separate book, how would you feel if the scope were broadened to "Documentation Guide"? (Or similar — not sure what to call it exactly.) With the Docs Guide idea, I envision a book with the following chapters:

• Overview - explaining how CiviCRM's docs are stored/published in separate books, and explaining how the languages and versions work for the books, in general. Some content from here plus a little more.
• Editing books - from here
• Adding a new book - yet to be written
• Using the publishing system - content from here plus a little more
• Markdown reference - from here
• Style guide - from here

The biggest challenge I see with this idea is the need (in an ideal world) to create redirects from the existing meta docs chapters in the Dev Guide to the hypothetical new chapters in the Docs Guide. Creating intra-book redirects has already been difficult and outstanding since Jan 5th. For inter-book redirects maybe we'd just manually add them to the nginx rules? @michaelmcandrew?

[seancolsen]

I'd like to make some progress towards resolving/closing this ticket, and I'd love to get some more thoughts from you @joannechester

Above I am proposing a separate guide which contain all documentation-related docs, but also raising some challenges with that approach.

Here's another idea... what if we re-branded the "Developer Guide" to the "Contributor Guide"? My thought here is that "Contributor Guide" would better encompass content about "how to write documentation". The scope of the guide would be broadened somewhat. This would help other content find a suitable home like "how to contribute to translation efforts". What are your thoughts on this idea, @joannechester ?

[stevekessler]

@seanmadsen As you and I discussed at Civicon without a method to search more than one book at a time having more books makes things harder to find in my opinion.

[seancolsen]

@stevekessler thanks for weighing in. I want to make sure I understand your opinion on this topic... It sounds like you're arguing against us creating a separate book like a "Documentation Guide", or a dedicated "Style Guide" book (in order to keep the total number of books low). Yes?

[stevekessler]

Yes. That is entirely correct. I think that fewer guides are better. Thanks, Steve

…

On Sat, Jun 3, 2017 at 10:14 AM Sean Madsen ***@***.***> wrote: @stevekessler <https://github.com/stevekessler> thanks for weighing in. I want to make sure I understand your opinion on this topic... It sounds like you're arguing against us creating a separate book like a "Documentation Guide", or a dedicated "Style Guide" book (in order to keep the total number of books low). Yes? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#140 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA0-kZjJfuT90Wys595xVG89mYxKZoM6ks5sAYZngaJpZM4LsDZM> .

[totten]

My votes:

• "Documentation Guide as separate book": Support
• "Doc guide within dev guide": Soft support
• "Rebrand dev guide as contributor guide": Oppose

Perspective: scoping the books seems like a subjective issue about trying to maximize the fit with audience+skillset+editors (while accepting that no arrangement would be perfect). This taxonomy feels cogent enough to me:

• "User" (someone with Office/Excel skills using the standard UIs)
• "Implementer" or "Site Builder" (someone comfortable with bash, tar, basic HTML, basic PHP, etc)
• "Developer" (someone comfortable with bash, git, PHP, JS, etc)
• "Documenter" (someone comfortable with Markdown and writing/composition/mechanics/rhetoric)
• "Translator" (someone bilingual/multilingual -- probably a User or Implementer)

The cross-book search issue is legit, but (a) I usually ignore built-in searches and go to Google, and (b) I suspect that combining more topics into a monolithic book will pose other issues (displaying too many nav elements or becoming too big for one person to administer).

Now... if someone could show that monolithic architecture actually works OK (wrt navigation and editorial workflow), then I'd flip-flop and go along with One Book To Rule Them All. But based on my current understanding, I'd vote for a taxonomy that accepts 3-5 books.

[dvhirst]

@totten - so does that mean you feel there should be 5 books; one for each of the groups mentioned? That starts to feel like "many" to me; I'd like to see some fewer number, but I'm not sure which combinations make the most sense; perhaps: User Guide, SysAdmin Guide, Developer Guide, Documentation Guide (with a section on translations); still feels like "many"...

@joannechester - I'd like to understand more clearly why you are not comfortable with combining the documentation elements (and possibly translations as well) into the developer guide. Three books feels about right to me.

@seanmadsen - agree that a decision sooner is better.

[joannechester]

I am definitely not in favour of keeping the documention elements in the Developer Guide.

It implies that a high level of coding skills is required to contribute to the user or sys admin documentation which is just not true. It could scare people off. It probably would have scared me off going to my first sprint.

I don't think it makes sense to decide on the "ideal" number of books and then force the topics we need to cover into that number of books. If there really is a concern about the number of books then my compromise is to just add one more - Documentation and Translation Guide.

[seamuslee001]

I am a +1 to Joanne's thoughts, i think a documentation and translation guide might be the best option

[seancolsen]

I think this would be a good one to chat about at the upcoming Docs Working Group meeting on 2018-04-03. I've added it to the agenda.

[joannechester]

Perhaps I need to revisit my statement

It implies that a high level of coding skills is required to contribute to the user or sys admin documentation which is just not true.

I have (once again) come up against the fact that github markdown and Mkdocs markdown are different. To make a substantial contribution to the user guide I need to have a Mkdocs installed locally and as a non-developer that is difficult. Now I remember that was final reason for the decline in my involvement.

[github-actions]

This issue has had no activity in 60 days and has been marked as stale, it will be closed in 10 days.

[dvhirst]

@michaelmcandrew -- I am uncomfortable with the automatic close of this topic. Is there any bandwidth in the new structure to keep it going? I'm OK with any decision taken about creation of a Documentation Guide and available to contribute to the editing process. Thanks. DVH

[homotechsual]

We have a style guide in the developer docs which covers all documentation books. Perhaps worth expanding that and linking to it from the other books?

[homotechsual]

https://docs.civicrm.org/dev/en/latest/documentation/style-guide/

With the updated docs-publisher and new version of MkDocs I can put a link directly to that page in the left hand nav menu.

[dvhirst]

That seems a reasonable approach. I liked Sean's list of topics haven't had a chance to check that they are all covered. Congrats on the new organization, it makes much good sense. DVH

[dvhirst]

@joannechester @michaelmcandrew -- I've now reviewed the current style guide against Sean's list from Feb 11, 2017. I find that it is in fact the referenced Style guide section from his list. Conclusion: no one has taken up the task of actually putting together the Docs Guide as envisioned in this open issue. I still think this is a worthy objective and am willing to sign up to assist in making it happen.

In particular, I'm not sure how a book is created and curious to find out. Perhaps this subject is a good learning exercise for me and possibly for others, with the end result being the desired Docs Guide. Anyone else interested?

BTW, I think this is a useful Chat>Docs Project post, so I'll make that happen, too. DVH

[homotechsual]

So I don't want to maintain the same content in the dev guide/sysadmin guide and user guide - and the style guide applies to all three. So perhaps this is worth splitting off into a separate book. However it is more discoverable to have the links in each guide.

So, options:

1. We could keep the content where it is and instead link to it from the user/sysadmin guides.
2. We could create a separate "docs" guide (is there enough content/demand for this?)
3. Some other solution I haven't thought of.

[michaelmcandrew]

I like the idea of 1.

The only downside of 1 over 2 is that it might create the a dev centric bias, but that can be countered and isn't worth an extra guide (unless someone wants to put the effort in).

The other random thought and fantasy I had is that we don't have a style guide for things like naming, UI design, etc. If and when we got there, it might be nice to have a separate broader style guide but I'm kind of in fantasy land here :)

[dvhirst]

I'm back thinking about this topic. There is already a starting place with the Style Guide material in place and as @MikeyMJCO mentions above, it is possible to link to it from the other guides. I'm interested in the process of setting up a new book, but that has a learning curve and takes time and effort. I'd rather put that time and effort into creating and organizing the necessary material. Once the material is available and in decent shape, if there's a decision that it belongs in a separate book, I'd imagine that creating the book metadata and moving the content to the new location is easily doable. So, I'm working on an outline for the new and revised content, and will begin the building process shortly. Perhaps this could be the start of the broader style guide that @michaelmcandrew would like to have. Thoughts?

[homotechsual]

That's fine, for the record if this ends up in its own book (or a revamped section!) we can merge in the docs-publisher documentation as well!