• bachmeier (23/23) Dec 28 2015 Is it acceptable to post examples/tips and tricks in the wiki,
• Rikki Cattermole (8/28) Dec 28 2015 I'm waiting for Andrei to respond but I think we can do one better.
• Vladimir Panteleev (6/11) Dec 30 2015 We had that at some point. Each documentation page had a
• bachmeier (6/18) Dec 31 2015 Perhaps it should be tried again. The language may have been

bachmeier <no spam.net> writes:

Is it acceptable to post examples/tips and tricks in the wiki, 
and then link to them in the official Phobos documentation? What 
I have in mind is adding to the documentation of a Phobos function

See Also: The [wiki](link) for additional documentation.

This would overcome two (valid IMO) complaints about the current 
system:

1. There is a lot of overhead associated with changing the 
official docs. With the wiki, you type in your new example and 
you're done. No futzing around for three hours over a period of 
several days to make a small change.
2. Dislike of Ddoc. The wiki uses markdown.

The wiki would accommodate helpful information that is not 
appropriate for the official docs:

1. Specialized examples.
2. Tips and tricks.
3. Guidance on choosing between available functions, like 
benchmarks.

The wiki has advantages over PHP-style user comments. The main 
one being that we can do it right now without having to change 
anything. Another being the fact that user comments shouldn't be 
part of the official docs, because they are unofficial, and are 
thus wiki material.

So is this something that we can do?

Rikki Cattermole <alphaglosined gmail.com> writes:

On 29/12/15 3:23 PM, bachmeier wrote:
 Is it acceptable to post examples/tips and tricks in the wiki, and then
 link to them in the official Phobos documentation? What I have in mind
 is adding to the documentation of a Phobos function

 See Also: The [wiki](link) for additional documentation.

 This would overcome two (valid IMO) complaints about the current system:

 1. There is a lot of overhead associated with changing the official
 docs. With the wiki, you type in your new example and you're done. No
 futzing around for three hours over a period of several days to make a
 small change.
 2. Dislike of Ddoc. The wiki uses markdown.

 The wiki would accommodate helpful information that is not appropriate
 for the official docs:

 1. Specialized examples.
 2. Tips and tricks.
 3. Guidance on choosing between available functions, like benchmarks.

 The wiki has advantages over PHP-style user comments. The main one being
 that we can do it right now without having to change anything. Another
 being the fact that user comments shouldn't be part of the official
 docs, because they are unofficial, and are thus wiki material.

 So is this something that we can do?

I'm waiting for Andrei to respond but I think we can do one better.

With a little bit of work we could on github ~master push update dlang.org.
So only need somebody to merge PRs or commit changes to ~master and it 
will auto be up there.

Travis-CI would be good for this. Unfortunately I don't know the OS and 
how it is setup let alone have auth rights. But it really shouldn't be 
too much work to do.

Vladimir Panteleev <thecybershadow.lists gmail.com> writes:

On Tuesday, 29 December 2015 at 02:23:27 UTC, bachmeier wrote:
 Is it acceptable to post examples/tips and tricks in the wiki, 
 and then link to them in the official Phobos documentation? 
 What I have in mind is adding to the documentation of a Phobos 
 function

 See Also: The [wiki](link) for additional documentation.

We had that at some point. Each documentation page had a 
corresponding wiki page. There are still remnants of this in the 
ddoc source (the WIKI macro).

It was hardly used, and the contents of wiki pages was almost 
always out-of-date, so it was removed.

bachmeier <no spam.net> writes:

On Thursday, 31 December 2015 at 07:41:05 UTC, Vladimir Panteleev 
wrote:
 On Tuesday, 29 December 2015 at 02:23:27 UTC, bachmeier wrote:
 Is it acceptable to post examples/tips and tricks in the wiki, 
 and then link to them in the official Phobos documentation? 
 What I have in mind is adding to the documentation of a Phobos 
 function

 See Also: The [wiki](link) for additional documentation.

 We had that at some point. Each documentation page had a 
 corresponding wiki page. There are still remnants of this in 
 the ddoc source (the WIKI macro).

 It was hardly used, and the contents of wiki pages was almost 
 always out-of-date, so it was removed.

Perhaps it should be tried again. The language may have been 
changing more back then. The current situation is that the 
official documentation doesn't get outdated only because it 
doesn't exist.