Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

proposal: unified godoc under zc.org #5

Open
wsc1 opened this issue Sep 3, 2018 · 4 comments
Open

proposal: unified godoc under zc.org #5

wsc1 opened this issue Sep 3, 2018 · 4 comments

Comments

@wsc1
Copy link
Member

wsc1 commented Sep 3, 2018

The zc projects don't have a unified view of all of zikichombo.org on godoc.org.

As one major goal of zc is simple, effective inter-op between the projects, it would be nice to host zc godoc in one place under zikichombo.org.

This way, we could also keep better tabs of what is of interest to consumers.

Thoughts?

Have the docs on gddo and zcdo? only zcdo? only gddo?
@mewmew
Copy link
Member

mewmew commented Sep 3, 2018

The docs should definitely be on GoDoc.org. Perhaps high-level design documentation can live on zc.org, and API docs on gddo?

@wsc1
Copy link
Member Author

wsc1 commented Sep 3, 2018 •
edited
Loading

The problems with gddo are

  1. that it doesn't present all the packages in one place. I'm not sure how to make it do that, although upspin.io shows up at godoc.org/upspin.io, so I guess it's possible, just don't know how to do it off hand.

  2. we don't have access to url request statistics for gauging how the documentation is serving those reading it, thus limiting our potential information for improving it. Maybe having it in both places would be a good compromise?

For high level design, so far I've been placing some of it in repo markdown files, which is independent of github (at least in sio) and more for us code monkeys than internauts. I think design documents like golang.org's articles on reflection and other topics would be great on zc.org website for zc specific topics.

@mewmew
Copy link
Member

mewmew commented Sep 3, 2018

I think they achieve this using a mono repo and a go-imports meta-tag at their web root.

view-source:https://upspin.io/?go-get=1

<meta name="go-import" content="upspin.io git https://upspin.googlesource.com/upspin">

From view-source:http://zikichombo.org/?go-get=1

<!DOCTYPE html>
<html lang='en'>

<head>
  <meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<meta name='description' content=''>
<meta name='theme-color' content='#dda0dd'>

<meta property='og:title' content='ZikiChombo'>
<meta property='og:description' content=''>
<meta property='og:url' content='http://zikichombo.org/'>
<meta property='og:site_name' content='ZikiChombo'>
<meta property='og:type' content='website'><meta property='og:updated_time' content='2018-08-03T19:26:43&#43;02:00'/><meta name='twitter:card' content='summary'>

<meta name="generator" content="Hugo 0.47-DEV" />

  <title>ZikiChombo</title>
  <link rel='canonical' href='http://zikichombo.org/'>
  
    <link href="http://zikichombo.org/index.xml" rel="alternate" type="application/rss+xml" title="ZikiChombo" />
...

@mewmew
Copy link
Member

mewmew commented Sep 3, 2018 •
edited
Loading

For high level design, so far I've been placing some of it in repo markdown files, which is independent of github (at least in sio) I think design documents like golang.org's articles on reflection and what not would be great on zc.org website.

Sounds good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@mewmew @wsc1