Intent to retire ReSpec docs site

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Intent to retire ReSpec docs site

Marcos Caceres-5
Hi ReSpec folks,
I'm in the process of migrating our old documentation site:
https://www.w3.org/respec/

To the ReSpec project's wiki:
https://github.com/w3c/respec/wiki

The new wiki now contains most of the existing documentation... should
finished the migration in the next few days.

🦄 I've also added usage-examples for every option.

Hopefully this makes it easier for people to both read, copy/paste
from, and contribute to the docs.

## What will happen to the old site?

We will just get it to redirect to the wiki.

## Why?
The old documentation site relied on a custom ReSpec build + some
scripts to generate the documentation. In order for people to
contribute, they had to do a number of very painful things:

 * clone the repo
 * install the tools
 * understand the new environment and where to make changes
 * create new HTML files,
 * etc.

Also, being a separate repo from the main repository meant that it was
too easy to just say "meh! I'll add docs later"... causing stuff to
get out of sync or never documented.

There are a number of other issues, but I won't bore you with them.
Now, just hit one button and you are editing... it's magic 🌈.

So, bookmark this and help us make the docs better!
https://github.com/w3c/respec/wiki

Again, we are always looking for people to help. Please jump right in :)

Kind regards,
Marcos

Reply | Threaded
Open this post in threaded view
|

Re: Intent to retire ReSpec docs site

Cody Burleson
Good move!


Sent from my iPhone

> On Jun 27, 2016, at 1:12 AM, Marcos Caceres <[hidden email]> wrote:
>
> Hi ReSpec folks,
> I'm in the process of migrating our old documentation site:
> https://www.w3.org/respec/
>
> To the ReSpec project's wiki:
> https://github.com/w3c/respec/wiki
>
> The new wiki now contains most of the existing documentation... should
> finished the migration in the next few days.
>
> 🦄 I've also added usage-examples for every option.
>
> Hopefully this makes it easier for people to both read, copy/paste
> from, and contribute to the docs.
>
> ## What will happen to the old site?
>
> We will just get it to redirect to the wiki.
>
> ## Why?
> The old documentation site relied on a custom ReSpec build + some
> scripts to generate the documentation. In order for people to
> contribute, they had to do a number of very painful things:
>
>  * clone the repo
>  * install the tools
>  * understand the new environment and where to make changes
>  * create new HTML files,
>  * etc.
>
> Also, being a separate repo from the main repository meant that it was
> too easy to just say "meh! I'll add docs later"... causing stuff to
> get out of sync or never documented.
>
> There are a number of other issues, but I won't bore you with them.
> Now, just hit one button and you are editing... it's magic 🌈.
>
> So, bookmark this and help us make the docs better!
> https://github.com/w3c/respec/wiki
>
> Again, we are always looking for people to help. Please jump right in :)
>
> Kind regards,
> Marcos
>
Reply | Threaded
Open this post in threaded view
|

Re: Intent to retire ReSpec docs site

Kostiainen, Anssi
In reply to this post by Marcos Caceres-5
> On 27 Jun 2016, at 09:11, Marcos Caceres <[hidden email]> wrote:
>
> Hi ReSpec folks,
> I'm in the process of migrating our old documentation site:
> https://www.w3.org/respec/
>
> To the ReSpec project's wiki:
> https://github.com/w3c/respec/wiki

Awesome work! Having contributed to these docs, even if already familiar with the environment, it still felt too tedious at times. Huge improvement.

Thanks,

-Anssi