Comments (26)
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.
from civicrm-user-guide.
Here's my logic for putting the style guide in the Dev Guide:
- 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).
- Markdown syntax differs slightly across platforms (e.g. GitHub does not support admonitions)
- 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.
- 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.
- Because of (1) and (4) it becomes necessary to choose one book to hold all meta-docs.
- We don't have enough meta-docs material to justify a dedicated book
- Because of (5) and (6) we should choose one of the guides (user, admin, or dev) to hold the meta docs
- All developers should be participating in documentation, at least to a small degree
- Very few users/administrators (who are not developers) will ever participate in documentation
- 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.
from civicrm-user-guide.
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 :)
from civicrm-user-guide.
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.
from civicrm-user-guide.
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).
from civicrm-user-guide.
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 :) )
from civicrm-user-guide.
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.
from civicrm-user-guide.
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?
from civicrm-user-guide.
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 ?
from civicrm-user-guide.
@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.
from civicrm-user-guide.
@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?
from civicrm-user-guide.
from civicrm-user-guide.
@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.
from civicrm-user-guide.
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.
from civicrm-user-guide.
I am a +1 to Joanne's thoughts, i think a documentation and translation guide might be the best option
from civicrm-user-guide.
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.
from civicrm-user-guide.
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.
from civicrm-user-guide.
This issue has had no activity in 60 days and has been marked as stale, it will be closed in 10 days.
from civicrm-user-guide.
@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
from civicrm-user-guide.
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?
from civicrm-user-guide.
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.
from civicrm-user-guide.
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
from civicrm-user-guide.
@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
from civicrm-user-guide.
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:
- We could keep the content where it is and instead link to it from the user/sysadmin guides.
- We could create a separate "docs" guide (is there enough content/demand for this?)
- Some other solution I haven't thought of.
from civicrm-user-guide.
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?
from civicrm-user-guide.
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!
from civicrm-user-guide.
Related Issues (20)
- Document the recommended CiviMail permissions for anonymous users HOT 3
- Document how to send an inline email image HOT 3
- Document accrual accounting, partial payments HOT 1
- Expand merging section to explain what happens to memberships when you merge contacts HOT 1
- Document Deferred Revenue HOT 1
- Clarify permissions for 'profile listings and forms' HOT 8
- Document all of CiviContribute Component Settings HOT 3
- Document CRM-19232: uploading docx/odt as message template HOT 1
- Documentation for Group ID is not (any longer?) accurate HOT 2
- Update ref to 'transgender' per https://lab.civicrm.org/dev/core/issues/993#note_18259 HOT 5
- Document passing parameters to CiviReport HOT 1
- Resource URL documentation is confusing and not updated for changes in 4.7+ HOT 1
- Document "smart group cache timeout" setting. HOT 3
- More info on weights etc in dedupe rules HOT 1
- CiviCRM User Guide Update: Understanding Unsubscribe vs. Opt Out HOT 1
- Tokens and click-through HOT 1
- Screenshot for event location page needs updating HOT 3
- Check and update localization instructions
- Document new CiviMail Tracking settings as per core PR #17291
- CiviMail workflow support is undocumented HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from civicrm-user-guide.