Documentation Working Group Charter (DRAFT)

We hope to finalize this by October 23, to leave ~2 weeks for community feedback.

It had been a while since I looked at the draft, but it still looks fine to me.

I've only participated in documentation stuff here and there, mostly sprints at 'cons -- so I'm basically just some guy. But this looks like a solid charter to me, FWIW.

You are "a contributing Drupal community member" you mean, not "just some guy". :) Thanks!

I did not participate in any other communication than this issue. However, the proposed charter makes too many assumptions and is not acceptable.

This charter fails to educate on the most important aspect: Responsibilities and decision authority.

What I read was a swath of mostly meaningless words, which were carefully chosen to NOT express any definite meaning.

I don't know what you want to resolve, but this does not appear to resolve anything and is unhelpful.

I'd suggest to replace this entire text with simple answers:

1. Who is responsible?

2. Responsible for what, exactly?

3. Where do responsibilities end, exactly?

4. What exactly is the decision authority of this group?

5. How are decisions made in case of a disagreement among group members?

6. What are the concrete duties that you "hope" to be worked on by members of this group?

Also, please define the term "documentation" and what exactly that encompasses. Your interpretation is definitely different than mine.

Hello, I would like to agree with Sun, and have broadly followed and added to his guideline with some mad copying and pasting. Please note that I've not added anything to the content itself, save some capitals, and one definition.

Documentation Working Group (DocWG) Charter

1. The aim of the group
1. Enable the community to create documentation for both core and contributed projects. This documentation should be accurate, complete, and maintainable. It exists primarily to help the community improve documentation by themselves.
2. Who is responsible
1. An informal group that includes anyone who works on Drupal-related documentation.
3. What are they responsible for?
1. Responsible for the policies, procedures, tools, and standards that are required to create and maintain documentation for the Drupal community.
2. Ensure that Drupal Core and Drupal’s contributed project ecosystem have excellent documentation-related guidelines, tools, and processes in place.
3. Maintain the guidelines and processes for documentation.
4. Recommend and guide development of tools and infrastructure that are needed for documentation.
5. Transparency
   1. The DocWG aims to be as transparent as possible by documenting its decisions publicly.
4. What are the limits of their responsibility?
   1. Does not necessarily create or apply the policies, procedures, tools and standards itself, but merely ensures that they exist, that they are well maintained, and that they are successful.
   2. Items specifically not within the scope of the DocWG's duties
      1. The DocWG is only responsible for the Community Documentation section on the main Drupal website not other drupal.org content such as general community policies, marketing collateral, etc. These would be under the purview of their respective working groups.
      2. The api.drupal.org policies, coding standards, and tools are excluded; however, the actual API documentation content follows the Drupal content style guidelines and the Drupal project coding standards.
      3. The DocWG cannot make technical policy decisions (this is the responsibility of the Technical Working Group) or community-wide governance decisions (this is the responsibility of the Governance Working Group)
      4. The DocWG cannot change or extend its own charter.
5. How do they act?
   1. They do so by engaging with the community in the following capacities:
      1. Documentation Team Processes:
         1. Maintains documentation and processes around how the documentation team works. This includes:
            1. membership
            2. communication
            3. how to work with individual project maintainers
            4. how documentation issues get resolved
         2. May also set up specific roles for members of this team.
   2. Tools
      1. May also develop guidelines and/or recommendations regarding the introduction of new tools, infrastructure, and technologies for the benefit of documentation.
      2. Where implementation of these recommendations is dependent on Drupal Association funding, Drupal.org integration, or significant investment from the infrastructure team, the DocWG will work with these groups to evaluate feasibility of any particular option or recommendation.
   3. Coordination and Colloboration
      1. The DocWG will work with other governance bodies on areas of common interest and overlapping responsibilities
         1. For Example: to ensure that there is a consistency of user experience and style across the documentation and non-documentation areas of drupal.org.
6. How are decisions made in cases of disagreement among group members?
   1. The DocWG acts as a group.
   2. 1. Proposing changes to existing policies and/or standards
      1. Any party who feels a policy or standard maintained by the DocWG is unreasonable may propose a change to the policy in question. Generally, modification proposals should solicit discussion and support from members of the Drupal community before being brought forward to the DocWG.
7. What is the decision authority of this group?
   1. Received proposals will be evaluated by the DocWG, and may be accepted, rejected, or referred back to the proposer with a request for further elaboration or community discussion on the issue. In some cases, the DocWG may refer the issue directly back to the community for further discussion before making a final decision.
   2. Individuals who do not agree with a given DocWG decision may escalate to Dries Buytaert and/or his designate(s), who will review the decision and can choose to either uphold or alter it. In the meantime, the decision of the DocWG stands.
8. Charter Revisions
   1. The charter will be revised as needed. Any proposed charter revisions must be ratified by Dries Buytaert and/or his designate(s) prior to acceptance into this charter. In the future, this charter may be revised to modify the charter revision process, subject to the aforementioned condition.
9. Definitions
   1. documentation:
   2. documentation-related guidelines:
   3. tools:
   4. processes:
   5. the community: Drupal developers and themers

My Personal opinions:

• I think Sun's question 6 "What are the concrete duties that you 'hope' to be worked on by members of this group?" is a repeat of "What are they responsible for?".
• I added my definition of the community but with all the Working Groups going on, is there a formal one?
• It would be nice to not have this content in a comment where other's can't edit it, but I'm not about to overwrite the current "original". Seems an issue.
• I'm not sure how I was suppose to write this comment but manually using ol's and li's was not it.

I would like to make the following suggestion, using an example.

Take one of the documentation issues I mentioned (at the bottom), regarding not being comfortable overwriting the current "original" of a document that is up for discussion. This appears like something that fits the scope of a DocWG.

After the DocWG discusses the issue, they can choose to:

• Decree there is no issue, and give their reasons.
• Decide that it is a valid issue and that having a "Current" version displayed beside a "Working" version would facilitate anyone to make changes, without impacting the original, improving collaboration without causing lengthy and time-consuming comment threads. It would also allow people to compare the states of each version.

The drafted DocWG, however, can only achieve the former. They are powerless to achieve the latter, which can only be decided upon by the Technical WG and the accounting department of Drupal.org.

I agree that the documentation needs working on. The current documentation suffers from being scattered and unedited. Much of the community puts useful documentation on their own personal blogs where they cannot be collaborated upon. The impact is that our community spends hours++ searching through tens to hundreds of articles for answers, rather than spending this time improving drupal websites. I believe this results from the structures used by our documentation.

Currently pages are designed so that commenting is much easier than editing. However, long comment streams must be completely read before a submission can be made. The goal should be to make editable documentation easier than comment streams.
Structures like side by side annotations of a document using fully capable nodes could achieve this. Like/Dislike buttons removes comments such as "Love ya work" from comment lists. Follow buttons remove the need for "Subscribing" comments. By changing the structures, the conversation is easier to follow and more definitive.

Changing documentation structures would create much more impact than a group working adding more documentation within the current system. These decisions, though, are made by the Technical WG and the accounting department.

So if a DocWG is needed I feel that it isn't a group. Rather it is currently a designated forum or book styled place for discussion on Drupal.org. This place is open to everyone who wishes to add their opinion.
It's purpose is:

1. To make a proposal to the Technical WG for structural changes to the website for how documentation is displayed and edited. These changes are to address the current issues caused by the current documentation system.
2. To provide a plain english guideline that shows how documentation is structured and how suggestions and changes are to be made.
3. To provide a 500 word or less, friendly guide describing the expected tone regarding how the community discusses issues within the documentation. Essentially a simple version of the previous item.

It would require:

• Two outlines of the constraints that it is working within, one from the Technical WG and one from the accounting department. Constraints should be understood as hard-limits that cannot be changed. Together, with the purposes defined above, they define the scope of the working group.
• A time limit within which to submit the proposal to the Technical WG and accounting department.
• The ability to advertise its intentions on the Drupal.org homepage.

A DocWG should work within the understanding that some items will be impossible within the constraints. Further changes, after the current list, would require the constraints to be updated by their respective authors.

Websites are structures for information. Changing the structures changes how people can use them.

This is all really good thinking, but I just want to note there's a distinction between the charters and the processes through which the governance groups conduct their day-to-day workings.

Charters are intended to lay the big stakes in the ground regarding what these groups are, what their aims are, what they are responsible for, and what they explicitly are /not/ responsible for. And that's basically it. This is because amending a charter is a "Really Big Deal"™ and it requires Dries's sign-off and a commit to Git, etc.

Versus some of the things you all are talking about: how decisions are made, where do they work, etc. are things best left to these WGs to define themselves. This allows them to be "agile" and pick a different process if the one they thought would work isn't working for them, etc.

That more "process/daily working"-oriented documentation for each group can be found under https://drupal.org/governance (still largely in process for a lot of groups since they're still in their "forming" phase). For example, https://drupal.org/governance/community-working-group under the Community Working Group.

Regarding the concrete example though, I don't think that this issue of whether or not you could just obliterate a proposal with something else would really be something in purview for the DocWG. For one, this is happening in an issue queue, not in the community documentation, so by definition is outside of their scope. For another, the DocWG as proposed doesn't exist to police individual pages, but rather to come up with processes and policies that enable the community at large to do their own policing. Any conflicts that arose would be resolved by either the Community WG (if it's a "people problem") or the Technical WG (if it's a "technical problem").

What someone *could* do though is if they saw someone go in and obliterate someone else's handbook page and thereby causing an "edit war," they could propose to the DocWG that "hey, we need a policy that says not to do that." The DocWG could consider adding such a policy, and also consider what feature changes to Drupal.org might be needed to support such a policy (for example, if you and another user have cross-edited a page more than 11 times in 30 seconds, lock the page from further edits for 4 hours), and work with the larger community to refine these recommendations.

Or, more specifically to your later point, the DocWG could work with documentation collaborators on a toolset to make editing pages easier than commenting, then approach the D.oSWG and say "yo, we need these things added to the D.o feature roadmap." And now the D.oSWG is hearing feature requests from an authoritative group of people who are able to speak on behalf of/represent a much *larger* group of people (everyone who works on docs) and advocate what's best for that group, as opposed to the D.o SWG having to understand every single nuance of every single tool on d.o and what works well and what doesn't, which is not really realistic, and often actually results in docs tools being marginalized in practice since the developers tend to be much louder than the documentation team about their tools sucking.

I think one thing you're saying though is you feel like this group should also have governing authority over the structure of the handbook, because the overall framework is unlikely to be changed by ad-hoc volunteers? So that would be an expansion of its proposed scope. Everything else though—a plain english guideline of how docs work, how (or if) to propose changes, documentation style guides, etc.—are all within its current stated scope.

Thank you for your replies Webchick. They help to provide context. In summary, the only role of this charter is to identify the aims of the group and what it is responsible for (www.drupal.org/documentation) and the boundaries of this responsibility. The methods that the group chooses to use in pursuit of these aims and responsibilities are determined by the group itself.

With that in mind, the intention of the current draft makes more sense. In some ways, much of my previous posts now seem to fit inside the discussion for the "process/daily-working"-oriented documentation for the group, post-formation. From your last paragraph Webchick, it appears I haven't explained myself very well, however my point would now appear off topic in light of the the role of charters and from re-reading the draft. In short, I firmly believe in facilitating others within the confines of "You can do anything, as long as...", seeing what crazy ideas come back, and then saying "Ok, have you talked to...?". I definitely believe in the power of ad-hoc volunteers. Much of Drupal is built off their efforts, yes?

My only suggestion is a re-write of a section of the draft, from the top down to the text "Specific duties of the DocWG". I consider this to only be a re-write of what already exists in the draft.

Documentation Working Group Charter

Mission

The mission of the Documentation Working Group (DocWG) is to help the community improve the documentation provided by the Community Documentation section, by themselves.

Scope / duties / responsibilities

Scope

The DocWG is responsible for policies, procedures, tools and standards for creating and maintaining documentation for Drupal Core and Drupal's contributed project ecosystem. This documentation is meant for the Drupal community.
The DocWG does not necessarily create or apply policies, procedures, tools and standards themselves, but rather ensures that they exist, are well maintained and that they are successful. Success is defined as when the community can create documentation that is accurate, complete and maintainable.

Specific duties of the DocWG

In addition to now understanding the purpose of charters, I have two more suggestions regarding why it was hard to initially understand.
It appears one of the difficulties in defining the scope of the group appears to be in regards to namespaces covered. It would be easy if the http://drupal.org/documentation namespace could be defined as the scope. However, that URL contains links to many other namespaces.
For me, another issue in understanding the charter now appears to be that the purpose of the documentation is not defined, just that it should exist.

I'd also like to put in an apology for misinterpreting the membership to the DocWG. I had considered them to consist of 'anyone interested'. However the draft charter actually implies they are a specific group of people who facilitate the documentation writers. It is these documentation writers ("documentation team") that consist of 'anyone interested'.

First of all, there appears to be hidden assumption that the DocWG is about drupal.org handbooks (http://drupal.org/documentation).

1. Is that assumption correct or not? — The charter MUST state the scope clearly.
2. If it encompasses other topics/areas, which exactly?

Charters are intended to lay the big stakes in the ground regarding what these groups are, what their aims are, what they are responsible for, and what they explicitly are /not/ responsible for.

Talks about goals and responsibilities, but none of that is clearly articulated in the proposed draft.

Perhaps the draft was meant to say what you meant (though what exactly did you mean?), but this draft uses language and terminology that appears to have been carefully chosen to not have any clear meaning.

In addition, lacking a concrete definition of responsibilities and decision authority, the DocWG's concrete relationship to the (already existing) Documentation Team (and its leaders) is anything but clear:

1. Who is in charge of what, exactly?
2. Who makes decisions on what, exactly?
3. Why does the existing Documentation Team need to be complemented with another group to begin with?
4. What happens if these two groups disagree? (And which party is supposed to discuss which topics?)

Versus some of the things you all are talking about: how decisions are made, where do they work, etc. are things best left to these WGs to define themselves. This allows them to be "agile" and pick a different process if the one they thought would work isn't working for them, etc.

Translation, based on the current draft:

1. We're setting up a working group that defines its working scope on its own.
2. We're setting up a working group that defines on its own how decisions are being made.
3. We're setting up a working group that defines on its own what to decide about.
4. We're setting up a working group that defines on its own on what to work on next.
5. We're setting up a working group that does not work on day-to-day operations, but is entitled to make decisions on behalf of all others, in whichever way they want, and encompassing whichever topic they see fit.

Sorry, that has nothing to do with "agile." That's the very definition of anarchy. Wasn't the goal to set up some more structure?

In regards to your first point Sun:

4.2.1: The DocWG is only responsible for the Community Documentation section on the main Drupal website not other drupal.org content such as general community policies, marketing collateral, etc. These would be under the purview of their respective working groups.

This section of text contains a hyperlink that refers to https://drupal.org/documentation. Perhaps the URL should be written out in full?

Wasn't the goal to set up some more structure?

Would someone provide some more context again please? I'm guessing something official-like has been written regarding what the point of the working group proliferation is. What type of structure?

Finally, in the section "Translation, based on the current draft", it is interesting to replace the words "working group" with "module project".

Reading through these comments and the proposed Charter, I think we should do a bit of editing. Because the first couple of sections just talk about "documentation" in general, and it isn't until you get down to Exclusions in the Specific Duties section that the scope is limited to the on-line documentation.

I also think that while it's *currently* limited to the "Community Documentation" section of drupal.org (which is everything under the book hierarchy at https://drupal.org/documentation), the Doc WG might hopefully in the future come up with a viable plan for a more curated documentation section/site, and this should be encouraged.

So... I would like to propose editing the charter as follows:

a) In the Mission, say "on-line documentation" in place of "documentation". So this would read:

The mission of the Documentation Working Group (DocWG) is to ensure that Drupal Core and Drupal’s contributed project ecosystem have excellent guidelines, tools, and processes in place for on-line documentation. The DocWG acts as a group to maintain the guidelines and processes for on-line documentation, and to recommend and guide development of tools and infrastructure that are needed for on-line documentation.

The purpose of these guidelines, tools, and processes is to enable the community to create on-line documentation for both core and contributed projects that is accurate, complete, and maintainable.

b) Same in Scope:

The DocWG is responsible for the policies, procedures, tools, and standards that are required to create and maintain on-line documentation for the Drupal community. The DocWG does not necessarily create or apply these instruments itself, but merely ensures that they exist, that they are well maintained, and that they are successful.

c) Similar edits are required elsewhere... I would be happy to make them if everyone agrees these are going in the right direction.

d) In Exclusions, first item:

The DocWG is only responsible for policies, procedures, tools, and standards related to the Community Documentation section of the main Drupal website (https://drupal.org/documentation), and other future on-line documentation sections and/or sites that they may initiate. They are not responsible for other drupal.org content such as general community policies, marketing collateral, etc. These would be under the purview of their respective working groups.

Thoughts?

x

Moving back to needs review.

Since 4 weeks had expired and no further feedback rolled in, Dries committed the charter to Git. Yay! Thanks, all.