Topics

How can we make use of the 'wiki' feature of groups.io? #admin

Chris Papademetrious
 

Hi all,

I see there is a 'Wiki' section of our dita-users group. This would be a handy place to collect how-to information. I would be happy to contribute some articles to get things started.

What's the best way for us to leverage this Wiki feature?

 - Chris

Kristen James Eberlein
 

Hi, Chris.

Right now, the Wiki functionality is set to the value that I selected when I set up the group: Subscribers can view, moderators can edit

I selected that option so that moderators could create a "sticky" Wiki page of guidelines for posting to dita-users that would be permanently visible atop of the messages on the Web site. (We obviously have not done so yet.)

The other choices for the Wiki functionality are as follows:

  • Public can view, Subscribers can view and edit
  • Subscribers can view and edit
  • Public and subscribers can view, moderators can edit
  • Wiki functionality is disabled

My concern about opening up the Wiki for general contribution is that Wikis usually get out-of-date pretty quickly. There's a lot of out-of-date info about DITA on the Web, and I don't want to contribute to it.

That said, I'm quite open to hearing discussion about this.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/4/2020 9:34 AM, Chris Papademetrious wrote:
Hi all,

I see there is a 'Wiki' section of our dita-users group. This would be a handy place to collect how-to information. I would be happy to contribute some articles to get things started.

What's the best way for us to leverage this Wiki feature?

 - Chris

Joe Williams
 


Kris makes a good point about the outdated information on the web. The DITA community is far from the worst in that regard, and I am reluctant to discourage anyone from an activity that could prove valuable.

A few years back there was some discussion about anticipating the demise of Yahoo groups and what action to take. Some of the group participated in an attempt to create a StackExchange, but there was not enough activity to get out of their Area 51 incubator. I had considered starting up a subreddit, but keeping such a site current would be a lot of work, and it is not a project I would take on. For me, the specification and the OT docs are my first source, followed by a Google search. If these don't turn up what i need, a post here or the OT list gets me what I need pretty promptly.

despopoulos_chriss
 

Kris brigs up the overarching problem with collective texts...  Curation...  Keeping things valid. I don't know enough about Wikipedia, but I do believe it's self-policing.  It's not clear that we could do something similar in our social group.  (I hate googling for tips on popular apps like Word, for example...  You never know what version the hits will pertain to.) 

That said, it would be cool to have a wiki corner for tips and techniques (for example).  If you include the DITA version you first used it on, then it could be resistant to version drift.  But it would still have a problem of moderation...  How do we identify advisable vs unadvised tips and techniques?  How do we ensure all the REQUIRED information is there (DITA version, other...)?  Moderator?  Group comments?  Is there a bar where a moderator can pull an article or delete a comment?  Who wants to moderate (it's a lot of work)? 

I think we could come up with some good uses for a general WIKI.  What's difficult is coming up with the rules and procedures.  And then coming up with enforcement.  Kris is right...  Nobody wants a social garbage heap.

Kristen James Eberlein
 

Wikipedia has very robust version control, which I suspect that Groups.io does not have. And Wikipedia also has a solid framework of processes and volunteer moderators.

Here is an idea that would not involved moderator effort (or at least no more effort than what we currently do.) I could create a #tips-and-techniques hashtag which could be used to classify e-mails that contained tips and techniques.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/6/2020 5:19 AM, despopoulos_chriss via Groups.Io wrote:
Kris brigs up the overarching problem with collective texts...  Curation...  Keeping things valid. I don't know enough about Wikipedia, but I do believe it's self-policing.  It's not clear that we could do something similar in our social group.  (I hate googling for tips on popular apps like Word, for example...  You never know what version the hits will pertain to.) 

That said, it would be cool to have a wiki corner for tips and techniques (for example).  If you include the DITA version you first used it on, then it could be resistant to version drift.  But it would still have a problem of moderation...  How do we identify advisable vs unadvised tips and techniques?  How do we ensure all the REQUIRED information is there (DITA version, other...)?  Moderator?  Group comments?  Is there a bar where a moderator can pull an article or delete a comment?  Who wants to moderate (it's a lot of work)? 

I think we could come up with some good uses for a general WIKI.  What's difficult is coming up with the rules and procedures.  And then coming up with enforcement.  Kris is right...  Nobody wants a social garbage heap.

Chris Papademetrious
 

Good discussion!

I was first tasked with learning DITA about 1.5 years ago. Indeed, by far the biggest obstacles were (1) locating information, and (2) finding non-outdated information. Many well-intentioned (but busy!) people have collected helpful information that has since aged - sometimes well, sometimes not.

There are plenty of examples of such fossilized DITA-related content around. But this group is active, and I believe it is a good opportunity to try a community-driven approach. As problems are solved and best practices are uncovered, content can be updated in-place to maintain relevance. This approach (incrementally updating reference content to reflect real-time Q&A) is very effective.

But what about questionable, incorrect, or malicious edits? According to this discussion about the groups.io wiki feature, "if there's a major problem, a moderator can delete the new page so it reverts to the older one." This is at least a basic level of moderation that we can use.

The hashtag approach is interesting, but posts can't be retroactively updated for relevance, the poster must remember to set the hashtag, and such flgged nuggets of information would not be available in a structured, readily-consumable form.

 - Chris

Kristen James Eberlein
 

I can bring this up with the other moderators. A key issue is whether we have bandwidth to manage a Wiki.

Another option is to add "Tips and techniques" info to the dita.xml.org site. That site is owned and maintained by the OASIS DITA Adoption Committee.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/6/2020 7:17 AM, Chris Papademetrious wrote:
Good discussion!

I was first tasked with learning DITA about 1.5 years ago. Indeed, by far the biggest obstacles were (1) locating information, and (2) finding non-outdated information. Many well-intentioned (but busy!) people have collected helpful information that has since aged - sometimes well, sometimes not.

There are plenty of examples of such fossilized DITA-related content around. But this group is active, and I believe it is a good opportunity to try a community-driven approach. As problems are solved and best practices are uncovered, content can be updated in-place to maintain relevance. This approach (incrementally updating reference content to reflect real-time Q&A) is very effective.

But what about questionable, incorrect, or malicious edits? According to this discussion about the groups.io wiki feature, "if there's a major problem, a moderator can delete the new page so it reverts to the older one." This is at least a basic level of moderation that we can use.

The hashtag approach is interesting, but posts can't be retroactively updated for relevance, the poster must remember to set the hashtag, and such flgged nuggets of information would not be available in a structured, readily-consumable form.

 - Chris

Ron Wheeler
 

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.

Tom Magliery
 

Hi Ron,

The first link you mentioned cannot be "fixed" per se. At least, that page can never be changed. It is a specification, not "documentation".

FWIW, there is a newer version of the DITA specification--version 1.3. Many changes and improvements were made to the specification from version 1.2 to 1.3. You can find version 1.3 here:

http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html

If you have suggestions for new DITA features or about the specification in general, they should be addressed to the DITA Technical Committee. In particular if they pertain directly to the specification, you should send comments to the "dita-comment" mailing list:
https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita#feedback

But if you are a DITA user (as opposed to someone developing applications that support DITA in some way) you may benefit more from reading documentation about your own DITA tools than from reading the DITA specification itself. 

mag

-- 
Tom Magliery


On 2020-01-12 16:58, Ron Wheeler wrote:

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.


Ron Wheeler
 

Thanks.


I am just a longtime user and use Eclipse (Spring Tool Suite) as my authoring environment.
I use standalone DITA-OT as well as the Maven plug-ins to publish my documents.

I do get by through Google which finds many useful pieces of documentation.

This discussion seems to have been prompted by a desire to create a new repository for DITA documentation oriented to actual use of DITA.

My point is that the documentation on the core organizations should be improved before we start a new wiki out of frustration.

Ron


On 2020-01-12 8:14 p.m., Tom Magliery wrote:

Hi Ron,

The first link you mentioned cannot be "fixed" per se. At least, that page can never be changed. It is a specification, not "documentation".

FWIW, there is a newer version of the DITA specification--version 1.3. Many changes and improvements were made to the specification from version 1.2 to 1.3. You can find version 1.3 here:

http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html

If you have suggestions for new DITA features or about the specification in general, they should be addressed to the DITA Technical Committee. In particular if they pertain directly to the specification, you should send comments to the "dita-comment" mailing list:
https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita#feedback

But if you are a DITA user (as opposed to someone developing applications that support DITA in some way) you may benefit more from reading documentation about your own DITA tools than from reading the DITA specification itself. 

mag

-- 
Tom Magliery


On 2020-01-12 16:58, Ron Wheeler wrote:

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.


Kristen James Eberlein
 

You are really missing the boat here. Please see my comments inline.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/12/2020 7:58 PM, Ron Wheeler wrote:
Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?
<kje>The OASIS DITA specification is a legal specification. It cannot be modified in any way after it is released; a specific version can be superceded by an errata or a DITA release. Is there a reason that you referenced version 1.2? DITA 1.2 was released over nine years ago, and it has been replaced by DITA 1.3, DITA 1.3 Errata One, and DITA 1.3 Errata Two.</kje>

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

<kje>The DITA specification is NOT end-user documentation. Its primary audience is implementors who build implementations of the DITA spec, such as DITA-OT and ditac. Given that audience, we certainly do our best to cover edge cases, as edge cases are where implementors might make different implementation choices.</kje>

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

<kje>Ironically, the topic that you mention in the DITA-OT documentation (https://www.dita-ot.org/3.4/topics/error-messages.html) cannot be out-of-date. The topic is programmatically generated from the code that stores the error messages. Thus, if DITA-OT has an error message, the error message is present in the DITA topic and thus the documentation. Now, I'm sure that some explanations are missing or can be improved; please see https://www.dita-ot.org/contributing for information about how to suggest edits to the documentation.</kje>

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

<kje>Yes, the dita-users group is mentioned at its then current location at Yahoo! Groups. At the time DITA-OT 3.4 was released, we were awaiting the transfer of the groups messages from Yahoo! to Groups.io. Please note the test version of the DITA-OT documentation correctly places the group at Groups.io.</kje>

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.

Chris Papademetrious
 

Hi Ron,

My suggestion to use the Wiki functionality has two important differentiating aspects:

  • We all visit this group often (versus being spread out across the Internets).
    • The information is available where the activity is, which also encourages discussion answers to be migrated to Wiki best-practice posts.
  • We can all contribute, update, and correct (versus the information being read-only).
I see plenty of outdated information about DITA on the Internet and many times I'm willing to update it but unable to do. Per Ron's observation that we're a community of technical writers, let's empower ourselves to make use of that skill set.

 - Chris