search

microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.71k stars 131 forks source link

Create Reference Website/Documentation. #262

Closed jginsburgn closed 3 years ago

jginsburgn commented 3 years ago

End users of TSDoc should have, alongside the TSDoc Playground an easy-to-access reference for the usage of keywords and examples. As of now, the specification must be learnt by reading through the code. This, however, is troublesome from the perspective of consumers who are not interested in writing the tooling but just using it. My proposal is to have an analogue to the documentation site of JSDoc or the eldest pioneer: Javadoc.

thefoodiecoder commented 3 years ago

This is a must to increase adoption. Currently many developers stay away from it due to unavailability of a reference documentation.

tifsolus commented 3 years ago

Any movement on this and or can some of us offer to assist with this ask. I wanna review adopting this, but as mentioned above, specs and or documentation is needed.

sg495 commented 3 years ago

Same here: I currently use https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/details/StandardTags.ts as a reference for tags, but that is definitely not the way to go for increased adoption. I am more than happy to create a draft of documentation page from that file: would a markdown file to link in README.md be suitable?

jginsburgn commented 3 years ago

@sg495 that is very kind of you! I think that would be a cornerstone. Later, if needed, a full website could be stemmed from there. What do you think?

octogonz commented 3 years ago

I think we should just stand up a proper website using https://microsoft.github.io/tsdoc/ which already hosts the playground. Then everything will be in nice markdown files that people can contribute to.

I had been delaying this because it would be really great to incorporate @rbuckton's parser updates before putting together a bunch of docs. But my time has been spread really thin this fall, so I barely have time to keep up with PRs.

In any case it is an engineer's vice to procrastinate a useful thing we could do real fast, in favor of an awesome thing that might be a long wait. Better to move forward in small steps.

Lemme see what I can put together.

jginsburgn commented 3 years ago

@octagonz thanks!

tifsolus commented 3 years ago

@octogonz Thank You

octogonz commented 3 years ago

You can follow my work-in-progress here:

https://microsoft.github.io/tsdoc-website/

MartynasZilinskas commented 3 years ago

@octogonz base tag is missing. All links are broken.

octogonz commented 3 years ago

Right, it is a work-in-progress. :-)

I'll update this thread when it's done.

jginsburgn commented 3 years ago

Dope! Looking good ;)

On Wed, Nov 25, 2020 at 03:03 Pete Gonzalez notifications@github.com wrote:

Right, it is a work-in-progress. :-)

I'll update this thread when it's done.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/microsoft/tsdoc/issues/262#issuecomment-733567652, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACQGHRNYCJDYXS3SKFHAUHDSRTB6XANCNFSM4SGK5H3Q .

octogonz commented 3 years ago

Status update: 🥳 Microsoft registered a DNS name for us: https://tsdoc.org/

The basic template and search are working, so now I just need to move the content over.

jginsburgn commented 3 years ago

Wow you’re really fast. Please tell me if you can use my help.

On Wed, Nov 25, 2020 at 21:27 Pete Gonzalez notifications@github.com wrote:

Status update: 🥳 Microsoft registered a DNS name for us: https://tsdoc.org/

The basic template and search are working, so now I just need to move the content over.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/microsoft/tsdoc/issues/262#issuecomment-734051876, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACQGHRN5TFBXSLQLZPI6Q3TSRXDJXANCNFSM4SGK5H3Q .

tifsolus commented 3 years ago

@octogonz; Awesome, super fast! Eco that, please let me know if you want to delegate any tasks. Be glad to help out.

Don

octogonz commented 3 years ago

Let me get the basic content sketched out, and then it would be super useful to have people review it for mistakes/wording, and point out areas that are unclear or incomplete. It is actually very difficult to find volunteers to carefully read a big pile of docs. And it's difficult for the author to edit their own writing because you get "snow blind" from reading it too many times heheh.

I'll follow up when it's ready. It's holidays right now in the US but we should be able to get this wrapped up pretty soon. Thanks!

tifsolus commented 3 years ago

Thank you for all the efforts on this. Sounds like a plan, take care and happy Turkey Day; just got done cooking mine. :)

octogonz commented 3 years ago

Progress update: I've published an initial writeup of the TSDoc tag definitions. I'll see if I can add some more specs over the weekend.

https://tsdoc.org/

octogonz commented 3 years ago

This PR integrates the TSDoc Playground: https://github.com/microsoft/tsdoc/pull/269

octogonz commented 3 years ago

Update: I've completed an initial draft of the website content. PR https://github.com/microsoft/tsdoc/pull/270 updates all the packages and README's to point to the new website.

This initial draft provides docs for every @ tag. But we don't yet have docs for the grammar or other mechanics issues. I'll aim to fill that out over the next few weeks as I find the time.

If anyone wants to help out by proofreading the pages and sharing questions/corrections/additions, that would be great! Please create your issues/PRs in the new repo: https://github.com/microsoft/tsdoc.org-website

BTW we've also created a #tsdoc channel in the Rush Stack chatroom, in case people want to discuss TSDoc more interactively. Might be fun!

Thanks everyone for inspiring me to get this done. 😋